<?xml version="1.0"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
 <head>
  <title>
   Howto: Run more than one instance of TorChat
  </title>
 </head>
 <body>
  <h1>
   How to run more than on instance of TorChat
  </h1>
  <p>
   <span style="color: #ff0000">This howto will <b>not</b> work with versions <b>below 0.9.9.260</b></span>
  </p>
  <p>
   First I will explain how torchat.ini and portable mode are working and
   where all relevant data files are located. Then I will explain some 
   things about adresses and port numbers of the client and the Tor proxy. 
   You should fully understand this before you go on to the second part 
   where we actually move files around and change some of the settings.
  </p>
  <p>
   Most of the this document is primarily targeted towards users of Microsoft
   Windows, because Windows is by far the most complicated operating system
   in existence. Users of Unix/Linux based operating systems can easily adopt
   all the information here for their platforms without problems.
  </p>
  <h2>
   Part 1 - How it works 
  </h2>
  <p> 
   The most important things are
  </p>
  <ul>
   <li>portable.txt</li>
   <li>torchat.ini</li>
   <li>the folder Tor</li>
  </ul>
  <p>
   I will now try to explain how this all works together.
  </p>
  <h3>
   portable mode or permanent installation
  </h3>
   <p>
    <b>Portable Mode</b> means that all that is needed is contained in one folder
    which you can carry around on an usb drive and run it wherever you
    happen to be. Therefore TorChat (for windows) comes bundled with its own 
    tor.exe which it will try to start and all settings and data files remain 
    inside this folder. Nothing will be copied or installed outside this folder
    to the computer's hard drive. The windows version you can download 
    is already preconfigured for Portable Mode out of the box. TorChat
    for *ix systems (including OS-X) has a little shell script "tor.sh" that 
    will do exactly the same thing as the windows "tor.exe" by starting a
    second instance of the Tor that is already installed on this machine, but
    with a special TorChat configuration (torrc.txt). The only difference on *ix
    is that you will have to install Tor yourself in order to be able to use 
    TorChat.
   </p>
   <p>
    Then there is the <b>Permanent Installation</b>. TorChat can be installed 
    to a read-only folder like c:\programs\ or /usr/* and all of it's data and
    configuration will be in %APPDATA%\torchat\ or ~/.torchat/
    In This mode TorChat will create a copy of the "Tor" folder in the data
    directory and use that instead just as it would use it in portable mode. 
    On *ix systems this Tor folder will contain the torrc.txt with the port 
    settings for this profile and the tor.sh to start an already installed
    tor service with this settings. On Windows systems it will contain it's
    own tor.exe instead of the shell script.
   </p>  
   <p>
    Finally there is another variant of operation, the <b>Client Mode</b> 
    This mode is only useful in rare special cases if you want to run TorChat 
    over some already running (and correctly configured) Tor proxy
    in your network or on your machine. This mode is for experts only.
   </p>  
   <p>
    The next few sections will explain how the mode is selected and how
    this is related to the configuration files.
   </p>  
  <h4>
   portable.txt
  </h4>
  <p>
   There is a file called portable.txt. It's contents are completely
   irrelevant, in fact it could be empty, only it's <b>existance is an
   indicator</b> wether TorChat should run in portable mode or not. If you delete
   this file, TorChat will store all it's data like the buddy-list and the
   configuration file in the user's <b>home directory</b>
   If the file portable.txt exists TorChat will look for all
   it's configuration and data in the same folder where torchat.exe 
   (or .py on *ix systems) is located.
  </p>
  <h4>
   torchat.ini
  </h4>
  <p>
   torchat.ini will be automatically created at the first start of TorChat or 
   whenever it has been deleted or moved and TorChat can not find it.
   Depending on wether the portable.txt is found or not TorChat
   will look for torchat.ini in the current directory or in the
   user's home directory. torchat.ini contains two sections
   <b>[tor]</b> and <b>[tor_portable]</b>. If TorChat was able to 
   successfully start the bundled tor.exe (or the tor.sh script on *ix)
   the section [tor_portable] is used, else it will use the settings in [tor]
   and you will have to configure the settings of your tor service yourself
   <b>including the hostname of the hidden service</b>.
  </p>
  <h4>
   The folder Tor
  </h4>
  <p>
   If we are in portable mode (portable.txt) TorChat will use the the Tor 
   folder that is in the TorChat directory and try to start
   Tor\tor.exe (or Tor/tor.sh) with the Tor configuration in Tor\torrc.txt.
  </p>
  <p>
   If we are not in portable mode TorChat will look for this Tor folder in
   the user's data directory (~/.torchat or %APPDATA%\torchat) and start it's
   tor service from within there.
  </p>
  <p>
   If you delete the tor.exe (or tor.sh on *ix) you can force TorChat into
   using an already installed Tor service on your network. This is the 
   <b>Client Mode</b>. It is not recommended for normal users. TorChat will 
   use the settings in [tor] instead of those in [tor_portable] and you
   <b>must</b> configure your Tor service manually <b>and</b> find the correct
   hostname (.onion address) and put it into torchat.ini <b>yourself</b>!
  </p>
  <h4>
   Summary
  </h4>
  <p>
   The whole thing could also be explained by some piece of pseudo-code:
  </p> 
  <pre>
    if found portable.txt:
        -> Portable Mode
        -> use current folder for all data
    else:
        -> Permanent Installation
        -> use home folder for all data
        
    if can start tor.exe (or tor.sh):
        -> normal mode of operation
        -> use settings in torchat.ini/[tor_portable] and torrc.txt
    else:
        -> Client Mode
        -> use settings in [tor]
        -> all must be configured manually!

  </pre>
  <p>
   	or if you are more attracted to tables we can summarize it in a tabular way:
  </p>
  <table border="1" summary="TorChat mode selection">
   <tr>
    <th>portable.txt</th>
    <th>Tor/tor.exe</th>
    <th>what will happen</th>
   </tr>
   <tr>
    <td><b>present</b></td>
    <td><b>present and working</b></td>
    <td><b>Portable Mode</b><br />
     all data and config in installation folder<br />
     settings in [tor_portable] are used</td>
   </tr>
   <tr>
    <td>missing</td>
    <td><b>present and working</b> (in profile folder)</td>
    <td><b>Permanent Installation</b><br />
     all data and config in home folder (~/.torchat or %APPDATA%\torchat)<br />
     settings in [tor_portable] are used</td>
   </tr>
   <tr>
    <td><b>present</b></td>
    <td>missing</td>
    <td><b>Client Mode (portable)</b><br />
     like Portable Mode<br />
     but settings in [tor] are used.<br />
     Only experienced users should use this, all has to be configured manually</td>
   </tr>
   <tr>
    <td>missing</td>
    <td>missing</td>
    <td><b>Client mode (permanent installation)</b><br />
     like Permanent Installaton<br />
     but settings in [tor] are used.<br />
     Only experienced users should use this, all has to be configured manually</td>
   </tr>
  </table>
  <h3>
   The configuration of Tor
  </h3>
  <h4>
   Normal operation, Portable Mode
  </h4>
  <p>
   In this Mode normally you don't have to configure anything. The
   Tor binary which is bundled with TorChat will be started with /Tor/torrc.txt
   as it's configuration file. Out of the box it is configured to listen on
   port 11109 (socks) and port 11119 (control) and to forward the hidden 
   service port 11009 to localhost:11009. Note that this are the same
   port numbers as configured in torchat.ini section [tor_portable]
  </p>
  <p>
   The hidden service directory is hidden_service
   inside the Tor folder. You may not change this.
  </p> 
  <p>
   If you plan to run a second portable instance on the same computer
   you will have to change all this port numbers and also the corresponding
   settings in torchat.ini section [tor_portable] and [client] in the
   <b>second copy</b> of the whole TorChat folder.
  </p>
  <h4>
   Normal operation, Permanent Installation
  </h4>
  <p>
   Everything is like in portable mode except for the location of the 
   configuration files torchat.ini and Tor/torrx.txt. They are inside your 
   profile folder (%APPDATA%\torchat\ on windows and ~/.torchat/ on *ix systems)
  </p>
  <p>
   Additionally you can use different profiles, if you start torchat with the
   name of a profile at the commandline. If you start TorChat with the 
   commandline</br>
  </p>
  <pre>
   torchat HansFranz
  </pre>
  <p>
   it will use the folder ~/.torchat_HansFranz/ or %APPDATA%\torchat_HansFranz\
   and have a copy of it's Tor folder in this directory, so you can change the
   port numbers only for this profile and will be able to run as much different
   profiles on the same machine as you want as long as you avoid conflicting
   port numbers.
  </p>
  <h4>Client Mode (not recommended)</h4>
  <p>
   You need to configure a hidden service in your existing Tor installation.
   To do this create a folder somewhere on your harddisk.
   For simplicity we just assume the full path to this folder is 
  </p>
  <pre>
   c:\foo\bar\onion1
  </pre>
  <p>
   put the following lines into your torrc:
  </p>
  <pre>
   HiddenServiceDir c:\foo\bar\onion1
   HiddenServicePort 11009 localhost:11009
  </pre>
  <p>
   Now restart your Tor service, make sure it runs without errors. While Tor is
   now running again in the background as normal, have a look into our hidden
   service folder we just created. There should be two files (which have been
   created by Tor). One is named <b>private_key</b> and one is named <b>hostname</b>.
   Inside this file (open it with notepad) you will find your <b>.onion address</b>.
   It will be something like <b>16crypticletters.onion</b>. Later on in this 
   document i will refer to this 16 cryptic letters as your .onion address.
   <span style="color: #ff0000">Put this .onion address (without the .onion at the end) 
   into your torchat.ini under own_hostname <b>or it will not work</b>. Otherwise 
   TorChat has no way of finding out what his own hidden hostname is.</span>
  </p>
  <p>
   Note: In the example above we have forwarded the hidden service 11009 to the
   <b>local</b> address localhost, port 11009. The <b>first</b> 11009 is the port
   "inside" the Tor network, never change this.
  </p>
  <h3>
   The configuration of TorChat
  </h3>
  <p>
   Torchat ist configured with torchat.ini. Where this file is located depends
   on the mode (portable or permanent, see above). Two sections in this 
   configuration file are of interest here: [tor_portable] and [client]. 
  </p>
  <p>
   The options in [tor_portable] tell TorChat how to reach your 
   tor proxy. They must correspond to SocksPort and ControlPort in the
   torrc.txt.
  </p>
  <p>
   The options in [client] tell TorChat where to listen for incoming
   connections. They correspond to the last part of the HiddenServicePort
   setting in your torrc.
  </p>
  <p>
   If you are running in Client Mode (delete tor.exe or tor.sh), which is
   not recommended for unexperienced users, then the settings in [tor] are
   used instead of those in [tor_portable]. In this mode you are rsponsable
   for configuring a hidden service manually and finding out the correct 
   setting for own_hostname <b>yourself</b>, which otherwise would be done 
   automatically.
  <h2>
   Part 2 - Some common scenarios
  </h2>
  <p>
   Now you have learned enough to actually make changes to the configuration.
   Following are a few common scenarios and how to configure them
  </p>
  <h3>
   A second instance in portable mode
  </h3>
  <p>
   I recommend that you start experimenting with this scenario until you
   feel confident with all the settings. You can always start out with a
   fresh copy of the bin folder if you think you have screwed it all up,
   you don't need to make any changes to files or configurations outside 
   this folder. The portable mode configuration is a great place to get 
   used to the Tor configuration without the danger of screwing up your 
   whole system.
  </p>
  <p>
   Scenario: You already have TorChat running in portable mode and you 
   want another instance of it running on the same computer with it's own 
   settings and buddy list.
  </p>
  <p>
   <b>Step 1:</b> Take your existing and already working copy and make a 
   second copy of the bin folder. This will become your second Full Portable
   instance.
  </p>
  <p>
   <b>Step 2:</b> Make this copy virgin again. Delete the file buddy-list.txt, 
   go to the folder Tor, delete the two folders hidden_service and tor_data
  </p>
  <p>
   <b>Step 3:</b> Configure the second Tor instance: We know that our ports 
   11009, 11109 and 11119 are already used so we think up 3 other numbers, 
   say 22009 (TorChat), 22209 (Tor socks) and 22229 (Tor control). Our torrc.txt
   should now be altered so that the relevant lines look like this:
  </p>
  <pre>
   SocksPort 22209
   SocksListenAddress 127.0.0.1
   ControlPort 22229
   HiddenServiceDir hidden_service
   HiddenServicePort 11009 127.0.0.1:22009
  </pre>
  <p>
   Note the last line: <b>HiddenServicePort <span style="color: #009900;">11009</span> 127.0.0.1:<span style="color: #990000;">22009</span></b>
   The first number is the TorChat Port <b>inside</b> the hidden network, it
   is never seen from the outside. It <b>must always be 11009</b> or TorChat would
   not work. Other clients will always try to connect to 11009. The second
   number is what is interesting for you, it is where you want this port to
   be <b>forwarded</b> to when it leaves the tunnel and enters the real world
   on your machine.
  </p>
  <p>
   <b>Step 4:</b> The configuration of the second TorChat instance. Open 
   torchat.ini with your text editor and change the relevant lines so that 
   they look like below (note that the settings in [tor] are not relevant 
   in Full Portable Mode):
  </p>
  <pre>
   [tor_portable]
   tor_server_control_port = 22229
   tor_server_socks_port = 22209
   tor_server = 127.0.0.1

   [client]
   own_hostname = xxxxxxxxxxxxxxxx
   listen_interface = 127.0.0.1
   listen_port = 22009
  </pre>
  <p>
   The setting own_hostname can be left alone. it will be updated 
   automatically. In Full Portble Mode TorChat will look into the
   hostname file, extract the hostname from it and automatically
   fill in the correct value. 
  </p>
  <p>
   <b>Step 5:</b> Try it out! It is time to start your second copy of TorChat. 
   It should start with an empty buddy list with only the newly generated 
   unique hostname as "myself" on it. Remember that it can take some time 
   until the myself-icon will become green. 
  </p>
  <p>
   If it doesn't become green after more than 15 minutes then there is 
   something wrong. If all your contacts get stuck in the state with blue 
   earth symbol and never turn green, then this is a sign that outgoing 
   connections work, but incoming connections don't work. In this case make
   sure that HiddenServicePort in torrc.txt and listen_port in torchat.ini
   are configured correctly.
  </p>
  <h3>
   A permanent installation with more than one profile
  </h3>
  <p>
   There is no windows installer yet, so if you are on windows, please
   always use portable mode instead and follow the instructions above.
  </p>
  <p>
   If you have installed the .deb package on debian, ubuntu or similar
   operating systems, and started TorChat for the first time then there
   sould be a folder ~/.torchat/ in your home directory. Inside this folder
   there is your torchat.ini and another folder 'Tor' with torrc.txt 
  </p>
  <p>
   Now quit this instance of TorChat. <span style="color: #ff0000">Never
   quit TorChat by hitting Ctrl-C in the terminal, always use "quit" from
   the menu, because TorChat must be able to properly stop it's child 
   process (tor.sh with tor) or you will have a tor process hanging around
   that will still provide it's hidden service and is bound to the ports
   it was configured to use.</span>
  </p>
  <p>
   Open a commandline window and type for example (use whatever name you want):
  </p>
  <pre>
   torchat JoeSixpack
  </pre>
  <p>
   TorChat will start again, but with a different ID and if you have a look
   into your home directory there will now be a second torchat folder named
   ~/.torchat_JoeSixpack. This is the profile folder of your alter ego
   Joe Sixpack, but if you try to start both instances at the same time it 
   will complain, you need to edit two files to make it work.
  </p>
  <p>
   See above under "A second instance in portable mode" and apply the steps
   3 to 5 to one of the two profiles to make sure that no port numbers are
   used twice. This way you should be able to configure and run as many
   instances as you like.
  </p>


  <h3>
   Using your already installed Tor service
  </h3>
  <p>
   yet to be written...
  </p>
  <h3>
   More than one instance using the same Tor service
  </h3>
  <p>
   yet to be written...
  </p>
 </body>
</html>
